<HTML><HEAD><TITLE>suspend(+Goal, +Prio, +CondList, -Susp)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Advanced Control and Suspensions</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>suspend(+Goal, +Prio, +CondList, -Susp)</H1>
Suspend the Goal and wake it with priority Prio as soon as one of the
conditions in CondList occurs.
<DL>
<DT><EM>Goal</EM></DT>
<DD>A callable term.
</DD>
<DT><EM>Prio</EM></DT>
<DD>An integer.
</DD>
<DT><EM>CondList</EM></DT>
<DD>A term of the form Vars-&gt;Cond or trigger(Atom) or a list of such terms.
</DD>
<DT><EM>Susp</EM></DT>
<DD>A free variable used to return the created suspension.
</DD>
</DL>
<H2>Description</H2>
   The specified goal Goal is suspended (a suspension is created as with
   make_suspension/3) and attached to the trigger conditions given in CondList.
   When any of the trigger conditions arise in the future, the goal is
   going to be woken up.
<P>
   The Prio argument determines the priority with which the Goal will be
   scheduled when woken. It can be a positive number between 1 and 12,
   or zero, in which case the priority defaults to the priority setting
   of the predicate which is called in Goal.
<P>
   CondList is a list of terms (or a single term) of the form Vars-&gt;Cond
   or trigger(Atom).  It specifies the conditions that will lead to the goal
   being woken up. It is enough for one of the specified conditions to arise
   in order for the goal to be woken.
<P>
   Vars-&gt;Cond is used to specify trigger conditions on variables.
   Vars is an arbitrary term, and the suspension will be attached to all
   the variables that occur in Vars. 
<P>
   The condition Cond is either the name of a predefined suspension
   list or the specification of a suspension list in one of the
   variable's attributes.  The predefined suspension lists are: 'inst'
   (for instantiation), 'bound' (instantiation, including aliasing to another
   variable) and 'constrained' (any constraining attribute modification).
   The general specification has the form
<PRE>
	Vars-&gt;moduleName:(suspListName of attrStruct)
</PRE>
    which can be abbreviated (if moduleName and attrStruct are identical) to
<PRE>
	Vars-&gt;moduleName:suspListName
</PRE>
    The following are examples for valid conditions:
<PRE>
	Vars-&gt;inst
	Vars-&gt;constrained
	Vars-&gt;fd:min
	Vars-&gt;fd:(min of fd)
</PRE>
   A specification of the form trigger(Atom) states that the goal should
   be woken by a symbolic trigger, ie.  by a matching invocation of the
   built-in schedule_suspensions/1.  The name of the trigger can be an
   arbitrary atom.
<P>
   The Susp argument returns a handle for the created suspension. This
   handle can, for example, be passed as an argument to the suspended goal
   itself, which is useful for demon goals which need to kill their own
   suspension under certain circumstances.
<P>
   NOTE: it is possible to create a suspension that can never be woken,
   e.g. by specifying a Vars-term without variables.
<P>

<H3>Modes and Determinism</H3><UL>
<LI>suspend(+, +, +, -) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(6) out of range </EM>
<DD>CondList is ill-formed.
</DL>
<H2>Examples</H2>
<PRE>
[eclipse]: suspend(writeln(hello), 2, X-&gt;inst, Susp),
        get_suspension_data(Susp, goal, Goal),
        get_suspension_data(Susp, module, Module).

X = X
Goal = writeln(hello)
Susp = 'SUSP-_321-susp'
Module = eclipse

Delayed goals:
        writeln(hello)
yes.


[eclipse]: suspend(writeln(hello), 2, X-&gt;inst, Susp),
        kill_suspension(Susp),     % killed before woken
	X=1.

Susp = 'SUSP-_308-dead'
X = 1
yes.



% A demon that wakes whenever X becomes more constrained
report(X) :-
      suspend(report(X, Susp), 1, X-&gt;constrained, Susp).

:- demon(report/2).
report(X, Susp) :-
      ( var(X) -&gt;
          writeln(constrained(X))   % implicitly re-suspend
      ;
          writeln(instantiated(X)),
          kill_suspension(Susp)     % remove from the resolvent
      ).
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/compiler/demon-1.html">demon / 1</A>, <A HREF="../../kernel/suspensions/make_suspension-3.html">make_suspension / 3</A>, <A HREF="../../kernel/suspensions/insert_suspension-3.html">insert_suspension / 3</A>, <A HREF="../../kernel/suspensions/suspend-3.html">suspend / 3</A>, <A HREF="../../kernel/suspensions/attach_suspensions-2.html">attach_suspensions / 2</A>
</BODY></HTML>
